feat(postgres): add Postgres.js tracing by BridgeAR · Pull Request #10125 · DataDog/dd-trace-js

BridgeAR · 2026-09-03T00:02:34Z

What does this PR do?

Adds automatic tracing for Postgres.js 3.x in CommonJS and ESM.

It starts spans when lazy queries enter a connection handler and finishes them at final Query settlement. Query identity and public methods remain unchanged.

The plugin reports compiled SQL resources, PostgreSQL database and endpoint tags, schema-aware names, peer service, truncation, and errors.

Motivation

Postgres.js is not currently instrumented, so applications using it do not emit database spans.

Its connection handlers and Query settlement functions remain in module-local closures, which makes runtime export wrapping incomplete.

Additional Notes

The real PostgreSQL matrix runs against 3.0.0 and 3.4.9 in CommonJS and ESM. It covers:

Unexecuted, deferred, mutated, and multiply-observed lazy queries.
Callback cursors, multi-batch async cursors, early return, and cursor errors.
COPY streams, file queries, build errors, server errors, and connection-ended errors.
Prepared-statement retries plus active and queued cancellation.
Transactions, reserved connections, concurrent pipelining, and parent propagation.
Multi-host metadata, naming schemas, service override, peer service, and truncation boundaries.

Postgres.js 1.x is excluded because it has a different internal architecture.

This does not add DBM propagation, AppSec query blocking, or a separate pool span.

Refs #2644

dd-octo-sts · 2026-09-03T00:03:24Z

Overall package size

Self size: 8.89 MB
Deduped: 9.56 MB
No deduping: 9.56 MB

Dependency sizes

| name | version | self size | total size | |------|---------|-----------|------------| | import-in-the-middle | 3.4.0 | 127.33 kB | 447.04 kB | | opentracing | 0.14.7 | 194.81 kB | 194.81 kB | | dc-polyfill | 0.1.11 | 25.74 kB | 25.74 kB |

_{🤖 This report was automatically generated by heaviest-objects-in-the-universe}

datadog-datadog-prod-us1 · 2026-09-03T00:05:49Z

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 98.18% (+0.01%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: c12c04a | Docs | View more details | Give us feedback!}

codecov · 2026-09-03T00:17:35Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.70%. Comparing base (2f698d5) to head (c12c04a).

Additional details and impacted files

@@           Coverage Diff            @@
##           master   #10125    +/-   ##
========================================
  Coverage   98.69%   98.70%            
========================================
  Files        1008     1012     +4     
  Lines      158514   158926   +412     
  Branches       74       74            
========================================
+ Hits       156448   156860   +412     
  Misses       2066     2066

Flag	Coverage Δ
ai-guard	`65.00% <35.46%> (-0.22%)`	⬇️
apm-capabilities	`63.71% <60.44%> (-0.01%)`	⬇️
apm-integrations	`81.58% <100.00%> (+0.09%)`	⬆️
appsec	`58.83% <36.87%> (-0.08%)`	⬇️
debugger	`69.85% <83.33%> (-0.01%)`	⬇️
instrumentation	`53.94% <70.93%> (+0.04%)`	⬆️
llmobs	`78.87% <35.46%> (-0.26%)`	⬇️
master-coverage	`98.70% <100.00%> (?)`
openfeature	`66.43% <83.33%> (-0.01%)`	⬇️
platform	`69.34% <83.33%> (+<0.01%)`	⬆️
profiling	`66.79% <83.33%> (-0.01%)`	⬇️
serverless	`65.57% <36.47%> (-0.18%)`	⬇️
test-optimization	`82.43% <35.46%> (-0.14%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pr-commenter · 2026-09-03T00:19:16Z

Benchmarks

Benchmark execution time: 2026-09-10 11:09:00

Comparing candidate commit c12c04a in PR branch BridgeAR/2026-09-03-postgres-js with baseline commit 2f698d5 in branch master.

📊 Benchmarking dashboard

Found 0 performance improvements and 0 performance regressions! Performance is the same for 2299 metrics, 14 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

🟩 = significantly better candidate vs. baseline
🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

Unstable benchmarks

These benchmarks have a confidence interval too wide to call a change; treat them as noise rather than signal.

scenario:appsec-iast-with-vulnerability-iast-enabled-default-config-20

unstable max_rss_usage [-21.004MB; +27.568MB] or [-5.948%; +7.806%]

scenario:debugger-enabled-but-breakpoint-not-hit-20

unstable cpu_user_time [-413.634ms; +657.248ms] or [-4.459%; +7.084%]
unstable execution_time [-414.567ms; +658.035ms] or [-4.465%; +7.088%]
unstable throughput [-1736766.692op/s; +1094695.511op/s] or [-6.427%; +4.051%]

scenario:debugger-line-probe-with-snapshot-default-26

unstable max_rss_usage [-12.934MB; +16.744MB] or [-5.413%; +7.008%]

scenario:encoders-0.4-immediate-flush-20

unstable max_rss_usage [-6.260MB; +11.337MB] or [-8.173%; +14.802%]

scenario:llmobs-encode-unicode-mixed-20

unstable max_rss_usage [-9067.859KB; +9154.259KB] or [-12.381%; +12.499%]

scenario:plugin-aws-sdk-eventbridge-inject-detail-24

unstable execution_time [-198.680ms; +325.003ms] or [-4.113%; +6.728%]

scenario:plugin-graphql-long-with-depth-and-collapse-off-24

unstable cpu_user_time [-664.741ms; +609.748ms] or [-6.043%; +5.543%]
unstable execution_time [-661.927ms; +618.269ms] or [-5.934%; +5.542%]
unstable throughput [-2.123op/s; +2.335op/s] or [-5.227%; +5.747%]

scenario:plugin-graphql-long-with-depth-on-max-26

unstable max_rss_usage [-24.047MB; +16.756MB] or [-12.457%; +8.680%]

scenario:plugin-pg-service-26

unstable execution_time [-99.544ms; +144.590ms] or [-6.096%; +8.854%]
unstable throughput [-434050.045op/s; +288432.531op/s] or [-6.351%; +4.220%]

wconti27 · 2026-09-03T15:21:27Z

 tracer.use('pg', { truncate: 5000 });
 tracer.use('pino');
+tracer.use('postgres');
+tracer.use('postgres', { service: 'postgres-service' });


we are moving away from allowing configurable per integration service name, can this be removed along with the optional configuration

I believe doing this only for some is not ideal. Otherwise it is likely confusing for customers. I believe it would also require special handling to prevent it (I believe it is a generic functionality)

Postgres.js keeps lazy queries and connection handlers in module-local closures. A Query can also settle after cursor replacement or retry. Instrument the source-owned dispatch and settlement boundaries to keep one span across queues, cursors, retries, and cancellations. Fixes: #2644

Postgres.js retains host and port values when a socket path is active, which made Unix-socket spans report a TCP endpoint that was not used.

Postgres.js uses whole-program transforms that do not share the generic transform contract.

jaisal1024 · 2026-09-12T04:29:39Z

the sentry implementation may be useful to peek at -> https://github.com/getsentry/sentry-javascript/blob/develop/packages/server-utils/src/integrations/postgresjs.ts
also would like native DBM support with sql comments added to spans like pg gives you

This would be an awesome feature!!

BridgeAR added the semver-minor label Sep 3, 2026

BridgeAR force-pushed the BridgeAR/2026-09-03-postgres-js branch 2 times, most recently from 8dcf731 to 51a4551 Compare September 3, 2026 15:08

BridgeAR marked this pull request as ready for review September 3, 2026 15:12

BridgeAR requested review from a team as code owners September 3, 2026 15:13

BridgeAR requested review from khanayan123 and wconti27 September 3, 2026 15:13

wconti27 reviewed Sep 3, 2026

View reviewed changes

Comment thread packages/datadog-instrumentations/src/helpers/rewriter/transforms.js Outdated

wconti27 reviewed Sep 3, 2026

View reviewed changes

BridgeAR marked this pull request as draft September 3, 2026 15:38

BridgeAR force-pushed the BridgeAR/2026-09-03-postgres-js branch from 51a4551 to 6d2af20 Compare September 4, 2026 23:21

BridgeAR marked this pull request as ready for review September 7, 2026 10:05

BridgeAR force-pushed the BridgeAR/2026-09-03-postgres-js branch from 6d2af20 to 3eac035 Compare September 8, 2026 11:56

BridgeAR added 3 commits September 10, 2026 12:45

fix(postgres): omit TCP tags for Unix sockets

9b8a4e8

Postgres.js retains host and port values when a socket path is active, which made Unix-socket spans report a TCP endpoint that was not used.

refactor(postgres): isolate rewriter transforms

c12c04a

Postgres.js uses whole-program transforms that do not share the generic transform contract.

BridgeAR force-pushed the BridgeAR/2026-09-03-postgres-js branch from 3eac035 to c12c04a Compare September 10, 2026 10:56

Uh oh!

Conversation

BridgeAR commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Additional Notes

Uh oh!

dd-octo-sts Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overall package size

Uh oh!

datadog-datadog-prod-us1 Bot commented Sep 3, 2026 • edited by datadog-prod-us1-3 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pr-commenter Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarks

Explanation

More details about the CI and significant changes

Unstable benchmarks

scenario:appsec-iast-with-vulnerability-iast-enabled-default-config-20

scenario:debugger-enabled-but-breakpoint-not-hit-20

scenario:debugger-line-probe-with-snapshot-default-26

scenario:encoders-0.4-immediate-flush-20

scenario:llmobs-encode-unicode-mixed-20

scenario:plugin-aws-sdk-eventbridge-inject-detail-24

scenario:plugin-graphql-long-with-depth-and-collapse-off-24

scenario:plugin-graphql-long-with-depth-on-max-26

scenario:plugin-pg-service-26

Uh oh!

Uh oh!

wconti27 Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

BridgeAR Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

jaisal1024 commented Sep 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BridgeAR commented Sep 3, 2026 •

edited

Loading

dd-octo-sts Bot commented Sep 3, 2026 •

edited

Loading

datadog-datadog-prod-us1 Bot commented Sep 3, 2026 •

edited by datadog-prod-us1-3 Bot

Loading

codecov Bot commented Sep 3, 2026 •

edited

Loading

pr-commenter Bot commented Sep 3, 2026 •

edited

Loading